How to read this document:

1) If you're familiar with Lingo, this reference will provide many real-world examples of how to use Beatnik effectively in your projects. Read through each method carefully, using the code examples as a basic guide for the many uses of each handler. The examples have been provided as real-world cases, ranging from courseware, to QTVR audio, gaming, internationalisation and many more.

2) If you're not familiar with Lingo, browse through this reference guide, looking particularly at the example code. The samples are designed so that you can cut-and-paste into your own projects, and adjust for your own variables. This way you can take advantage of the power of the Beatnik Xtra with minimal fuss.

Brief feature summary:

The Beatnik Xtra is ideal for Enhanced CDs, gaming, interactive courseware, backing music tracks, ShockWave and general graphic user interface audio/music. Giving you up to 32 sound channels on both Macintosh and Windows platforms, with extremely low latency performance and extremely low CPU overheads, Beatnik's performance is typically superior to using DirectX or QuickTime Music. Combining a high quality, high performance software wavetable synthesiser with a state-of-the-art audio mixer, Beatnik is able to play MIDI/RMF files with their incredible bandwidth efficiencies, as well as intermix samples within RMF, AIFF, WAV, MOD and AU files. Custom instruments for the MIDI soundbank can also be created easily with quality development tools. An optional MOA mixer mode enables Beatnik audio to be intermixed with normal Director audio including ShockWave Audio, sound playFile commands, and Flash audio etc.

Advanced features such as stereo panning, sample and song transposition, track mutes/solos, reverb effects, synchronisation with Lingo based events/animations open Director up to the world of interactive audio features not previously available.

The Beatnik Xtra adds a large number of new Lingo statements that create and communicates with Beatnik 'musicObjects.' Imagine a 'musicObject' to be a type of intelligent and invisible cast member, with an extensive list of properties that can be set or read. Like a virtual band-for-hire with its own autonomy, you control the 'musicObject' band with extensive Beatnik Lingo commands.

Each musicObject is capable of interactively playing back Rich Music Format (RMF) or MIDI files of up to 64 tracks. As well, the musicObject is compatible with AIFF, WAV, AU and MOD files, albeit without the compression, full interactivity, 40bit encrypted watermarking and digital effects advantages of the RMF format. Of course you may convert MIDI, AIFF, WAV, AU and MOD files to the RMF format using the Beatnik Convertor for Windows or the Beatnik Editor for Macintosh.

How do I use it?

You can create as many musicObject instances as you like in a Director movie. While there is also no strict limit on the number of Beatnik musicObjects instances created per Director movie, simultaneous playback is limited to eight musicObjects. If you are going to create many musicObject instances, you should be aware that for each musicObject instance there is a modest minimum amount of memory that is needed on the user's system. In addition, when a musicObject instance loads its music or audio file, that file must then be contained in the user's memory.

So, while there are no forced limitations on the number of musicObject instances created from the Beatnik Xtra, you should be careful not to create movies that make such heavy demands on the user's memory resources that it become sluggish and unbearable to use.

Before any Lingo handlers can be accessed, you must first create a instance of the Beatnik musicObject that you subsequently refer to. An instance is like a 'ghost copy' of the musicObject - all the handlers contained in the Beatnik Xtra's musicObject are automatically copied to your own created instance - thus you may call your own instance, trusting that it has been automatically imbued with new and extensive audio Lingo methods. (Using the correct Object Orientated Programming terminology, all subsequent handlers of the musicObject in this document are called 'methods' of your 'instance'.)

To have Beatnik-enabled music in your Director project, you must also include the Beatnik Xtra and the Headspace soundbank "Patches.hsb" file in your project. The Xtra can be included in the Xtra folder at the same level as the Projector, or 'opened' with the openXLib command via Lingo. You may also include the Xtra inside your Projector, but you should be aware of some issues under the 'including Xtras within Projectors' option under Director 6. The Headspace sound bank file "patches.hsb" can be located anywhere and referenced via pathname using the setSampleLibrary command, but it is recommended to keep this file in the same directory as your projector or Xtra in order to keep file management simple.

In the quick reference table below, the Beatnik Player's supported musicObject methods are divided into the following main groups:

• Initializing the Xtra - Instance management
• Song Control and Player Properties
• Playing Individual Notes
• Realtime Control of Files
• General Playback State

You can click on each method name to get detailed information for that method, or you can click on one of the group headings to start reading in detail about that group of methods.

Some musicObject methods are not supported (or do not have meaning) for some of the Beatnik Player's supported file types. The columns to the right of the method column indicate which file types the methods are supported for.

Initializing the Xtra - Instance management

The Beatnik audio engine's functionality is implemented within Director through the Macromedia Open Architecture as a Lingo Xtra. Rather than appearing as a new Cast Member asset type, the extensive controls for handling audio appears as new Lingo handlers, able to refer a musicObject instance. A Beatnik musicObject instance is created for each audio player, and multiple musicObjects may be created within a Director movie. Only eight musicObject instances can be played simultaneously through the audio engine however.

VERY IMPORTANT: Before any Lingo handlers can be accessed, you must first create a instance of the Beatnik musicObject that you subsequently refer to. An instance is like a 'ghost copy' of the musicObject - all the handlers contained in the Beatnik Xtra's musicObject are automatically copied to your own created instance - thus you may call your own instance, trusting that it has been automatically imbued with new and extensive audio Lingo methods.

The sample code below gives a recommended approach to creating an instance of the Beatnik musicObject.

Sample Code:

on startMovie
   global groovySong
 
   if ilk(groovySong) = #instance then stop(groovySong)
   set groovySong = VOID
 
-- create new instance of Beatnik called "groovySong"
   set groovySong = new(xtra "beatnik")  
   if not(objectP(groovySong))
       alert("Beatnik musicObject instance creation failed")
   end if 
 
-- setup buffer size and sample library's location
   setSliceSize  (groovySong,5)
 
   set bankFileName = the moviePath & "Patches.hsb"
   setSampleLibrary(beatnik,  bankFileName)
 
   setReady(groovySong)
 
-- check to see that Beatnik initialized correctly
   if not(isReady(groovySong)) then
      alert "Beatnik did not initialize."
      exit
    end if
end startMovie
  

on stopMovie
   global groovySong
   stop (groovySong)
   closeBeatnik (groovySong)
   set groovySong = VOID
end stopMovie
   

For example, by executing: set myMIDISong = new(xtra "beatnik"), the variable myMIDISong becomes an instance of the Beatnik Xtra's musicObject and inherits all methods listed in this document relevant for controlling MIDI song. Each musicObject instance that you create will use a small amount of memory (as a 'ghost' copy of the parent musicObject). When you have finally finished with each of your musicObject instances, you should free the memory allocated to it by declaring the variable equal to VOID. eg. set myMIDISong = VOID. By stopping the musicObject, shutting it down and freeing the memory, you also will flush any remaining audio in the Beatnik audio buffers. If you fail to do this last step, the next time you create the instance, you'll momentarily hear the remaining buffered audio.

When you create an instance of the musicObject, you can specify whether it will play Direct-to-soundcard (DTC) or use the Macromedia Open Architecture's mixer (MOA). By default, new instances are created to go Direct-to-card. Specifying new(xtra "beatnik") without the second parameter is equivalent false (DTC.) The DTC mode has great advantages in response speed compared to MOA mode, as the Headspace Audio Engine has been designed to typically take up 1% of CPU time on an equivalent 100MHz Pentium processor. If you require Director audio to play simultaneously with Beatnik, creating a musicObject in MOA mode will enable this to occur, albeit with lesser performance. It is recommended that setSliceSize be set to a higher value in MOA mode so that sound breakup does not occur. You cannot have a number of instances that mix DTC or MOA mode - all instances must be set to the same mode, or silence will result. However, to effectively use Beatnik and MOA audio in your projects, you may selectively create and destroy musicObject instances at various points to take advantages of each audio mode.

Note:

The new(xtra "beatnik") statement is not optional. A musicObject instance must be created for your targetted filetype, regardless of whether it is RMF, MIDI, AIFF, WAV, AU or MOD.

Sample Code:

-- this movie has two musicObject instances. 
-- the instance called "mySoundTrack" will the musicObject 
-- that plays the backing music, the instance 
-- called "interfaceSounds" will contain special button 
-- and transition sounds created with custom samples in a RMF file. 
-- you can call your own instances whatever you'd like so long
-- they are valid Lingo variable names

on startMovie 
-- your instances need to be global variables to be able
-- to be referred throughout the entire movie
   global mySoundTrack 
   global myInterfaceSounds 
-- create mySoundTrack instance in Direct-to-card mode
   set mySoundTrack = new(xtra "beatnik")
-- create myInterfaceSounds instance in Direct-to-card mode
   set myInterfaceSounds = new(xtra "beatnik")
end startMovie 

-- control of the backing music is accomplished by referring 
-- to the global variable "mySoundTrack" 
-- for example: 
on enterFrame 
   global mySoundTrack
-- alters volume of the backing music 
   setVolume(mySoundTrack,integerVolumeLevel)
-- plays backing music
   play(mySoundTrack)
end enterFrame 

-- user interface sounds can be controlled by referring 
-- to the global variable "interfaceSounds"
-- for example:
on mouseUp 
   global myInterfaceSounds
-- play on MIDI channel 16, user bank 2, program 1,
-- a middle C note at max velocity for 0.5 seconds
   playNote(myInterfaceSounds,16,2,1,64,127,500)
end mouseUp

on stopMovie
   global mySoundTrack
   global myInterfaceSounds
   stop(mySoundTrack)
   stop(myInterfaceSounds)
   closeBeatnik(mySoundTrack)
   closeBeatnik(myInterfaceSounds)
-- declaring each musicObject instance to equal VOID will
-- free up the memory allocated for the child instance
   set mySoundTrack = VOID
   set myInterfaceSounds = VOID
end stopMovie 

The setSampleLibrary() method sets the location of the default sample library (Patches.hsb) used for the General MIDI (GM) and Special sound banks built into the Beatnik Xtra. Samples within User Instruments are not stored in the Headspace Sample Bank (Patches.hsb) but instead are encapsulated with a 40bit encrypted watermark in a Rich Music Format (rmf) file. Refer to the documentation for the Beatnik Editor for Macintosh and the Beatnik Windows Convertor for more information about creating your own custom RMF files with custom samples.

Sample Code:

-- patches.hsb file is located in the same directory
-- as the Director Projector
set bankFileName = the moviePath & "Patches.hsb"
setSampleLibrary(beatnik, bankFileName) 

The getSampleLibrary() method finds location of the default sample library (Patches.hsb) used for the General MIDI (GM) and Special sound banks built into the Beatnik Xtra. Samples within User Instruments are not stored in the Headspace Sample Bank (.hsb) but instead are encapsulated with a 40bit encrypted watermark in a Rich Music Format (rmf) file. getSampleLibrary() is designed primarily for ShockWave delivery of Beatnik content using the Beatnik Xtra - as the Patches.hsb bank would be already installed into a end user's system, one only need to check via getSampleLibrary(), if it's not available, the content provide would initiate a smart updating process. The Beatnik Xtra without the hsb bank is approximately 150K in size for both Macintosh and Windows platforms, so a requested download/upgrade would not be a strenous effort.

Sample Behaviour:

-- NO LIBRARY SET, NO BANK FOUND IN CURRENT FOLDER OR WINDOWS FOLDER:
put getSampleLibrary(beatnik)
-- Void

-- if Patches.hsb is present in system folder
put getSampleLibrary(beatnik)
-- "C:\WINDOWS\Patches.hsb"

-- Setting one explicitly
setSamplelibrary(b, "n:\beatnik\Patches.hsb")
put getSampleLibrary(beatnik)
-- "n:\beatnik\Patches.hsb"


Finding one in current folder:

set currSoundBank = getSampleLibrary(beatnik)
if voidP(currSoundBank) then
  alert "Can't find a sound bank!"
  exit
end if 

The setSampleLibrary() method sets the location of the default sample library (Patches.hsb) used for the General MIDI (GM) and Special sound banks built into the Beatnik Xtra. Samples within User Instruments are not stored in the Headspace Sample Bank (.hsb) but instead are encapsulated with a 40bit encrypted watermark in a Rich Music Format (rmf) file. Refer to the documentation for the Beatnik Editor for Macintosh and the Beatnik Windows Convertor for more information about creating your own custom RMF files with custom samples.

Sample Code:

-- Patches.hsb file is located in the same directory
-- as the Director Projector
set bankFileName = the moviePath & "Patches.hsb"
setSampleLibrary(beatnik, bankFileName) 

Initialize Beatnik Engine.

Closes down Beatnik Engine. Should be done when closing off a musicObject instance, and declaring the instance to be VOID. This will avoid any possible conflicts with the Director engine.

Checks to see if Beatnik musicObject instance (and its underlying Headspace Audio Engine's instance) is initialized. Returns a boolean TRUE or FALSE and can be used to poll the Headspace Audio Engine for the specified musicObject instance to determine if it's ready to play and be affected through musicObject methods, with true indicating that it is ready for playing.

Sample Code:

-- do not proceed until isReady(beatnik) is true
repeat while not(isReady(beatnik))
   nothing
end repeat

Returns a string corresponding to the error code passed from a method. By setting the method to a variable and testing if the returned variable is zero ie. not(FALSE) (also evaluated to not equal to zero), one may proceed to an error handler.

Sample Code:

global errorCode
-- if myFile = "", then errorCode = -11 (ie. File Not Found)
global myFile = ""

-- sample test handler
on loadFile
   set errorCode = playFile(beatnik,myFile)
   if not(errorCode) then debugError
end loadFile

on debugError
   global errorCode
   set alertString = getErrorString(beatnik,errorCode)
   alert alertString
end debugError

Song Control and Player Properties

This section describes methods useful for implementing general user interface controls, as well as controlling playback of music tracks, atmospheric soundbeds and audio transitions.

Syntax:	fadeFromTo(objectMe, startVolumeInteger, endVolumeInteger, [fadeTimeMilliseconds])
Example:	fadeFromTo(beatnik,1,100)
Related:	fadeTo

fadeFromTo will fade the volume level of the targeted file from a specified initial volume level to a specified final volume level. If the "from" volume level is much different to the current volume level of the playing file, there will be a noticeable glitch as the volume changes initially and then begins to fade. The [fadeTimeMilliseconds] parameter is optional - if not specified, the Beatnik Xtra will use a default value of 0.1 second. Although the function is termed "fade" - both fading up and fading down is easily accomplished by setting the volumes to ramp up or down. Allowed values of the volume integer are 0 to 100 inclusive. This function controls the volume output of the Xtra and is different to the MIDI channel volume Controller 7 changes.

Note:

If the targeted file is not currently playing or is in a pause state, this method will have no effect.

Sample Code:

on crescendo
   global ambience
-- fade up from silence to max over 5 seconds
   fadeFromTo(ambience, 1, 100, 5000) 
end crescendo

fadeTo will fade the volume level of the targeted file from the current volume level to a specified final volume level. The [fadeTimeMilliseconds] parameter is optional - if not specified, the Beatnik Xtra will use a default value of 0.1 second. Although the function is termed "fade" - both fading up and fading down is easily accomplished by setting the end volume to ramp up or down from the current volume level. Allowed values of the volume integer are 0 to 100 inclusive. This function controls the volume output of the Xtra and is different to the MIDI channel volume Controller 7 changes.

Note:

If the targeted file is not currently playing or is in a pause state, this method will have no effect.

Sample Code:

on fadeMusicDuringVoiceOver
   global musicFile
-- 1.8 second fade down to 30% volume from current volume level
   fadeTo(musicFile, 20, 1800) 
end fadeMusicDuringVoiceOver

Syntax:	getAutostart(objectMe)
Example:	getAutostart(beatnik)
Related:	setAutostart

Returns the autostart property of the Beatnik Xtra instance. This property is set initially using the setAutostart method, or defaults to TRUE. Since the setAutostart method is useful for preloading musicObject files, you may have a number of musicObject instances that are dynamically used for preloading or playing. getAutostart may be used to query each instance for the autostart property.

Sample Code:

on checkAutoStart
   global myInstance
   set x = getAutostart(myInstance)
   set y = isPlaying(myInstance)
   set z = isPaused(myInstance)
   -- if all three above properties are false, then file is stopped
   -- musicObject instance has not been set to autostart
   if (not(x) and not(y) and not(z) then
      play(myInstance,"jungle.rmf")
   end if
end checkAutoStart

Gets information about the song currently loaded by the targeted musicObject instance. The string parameter passed to this method indicates the specific field of the song information contained in an RMF file. The possible field names are listed in the table below. Field names are not case-sensitive. If no string is declared, the current version number and details of the Xtra will be returned.

Note:

This method has no meaning for file types other than RMF and will return a null string. A null string will be returned if an invalid field name is specified.

Sample Code:

on displayTrackName
   global mySong
   set RMFtitle = getInfo(mySong, "title")
   put RMFtitle into member "textCastMember"

end displayTrackName

Sample Code:

on checkXtraVersion
   global beatnik
   alert getVersion(beatnik)
end checkXtraVersion

Pauses the targeted file so that it may be resumed using the pause or play methods. Once a file is in pause mode, the isPaused property is set to true. The optional second parameter fadeTimeMillisecondsInteger will ensure that the song pause occurs after the milliseconds fade time specified.

Sample Code:

on mouseUp
   global currentPopSong
-- toggles the pause state of my song
-- if playing, song will pause after a fade time of 0.75 seconds
-- if paused, song will restart instantly from last song position
   pause (currentPopSong, 750)
-- check to see if file is paused and display "paused" graphic
   if (isPaused(currentPopSong) then
      set the visible of sprite 8 to TRUE
   else
      set the visible of sprite 8 to FALSE
   end if
end mouseUp

This method will load the specified file into memory - depending on the setAutostart status, the file will either start playing automatically, or wait till a play command is initiated. Thus by using setAutostart(objectMe, FALSE), preloading of Beatnik music and sound files can be accomplished.

When used with no second or third parameters, play will start the targeted file playing. If the targeted file is already playing, this method will be ignored. Also, if a file has been put into pause mode with the pause method, play will make the file resume playing.

Sample Code:

on mouseUp
   global technoBacking
-- play current song
   play(technoBacking, TRUE, the moviePath & "techdance.rmf")
   go to frame "technoDancers"
end mouseUp

Similar to the play method excepting that the file to be played is a Groovoid which is contained inside the Beatnik sound bank. Groovoids are a collection of "pre-cooked" musical cues, background music, and user-interface type musical effects that comes bundled with the Beatnik Xtra.

What's so great about Groovoids?

• They are always local to the user's system and so are triggered immediately. Because they are based in memory, they are useful for providing instant user-interface sounds, accompany transition effects with music cues, or provide some audio backing whilst you preload other media assets off your hard drive or CD-ROM or online ShockWave assets.
• Groovoids are FREE! They are yours to use on your Director project with no strings attached. There's no need to pay any license or "drop" fees, and you never have to report usage.
• There are 60 of them in the free Lite version of the Beatnik Xtra, designed for a wide variety of uses, ranging from user-interface feedback sounds to transitions, atmospheric sound beds, jingles and bumpers.
• If you upgrade to the Beatnik Xtra Pro, you'll get 120 Groovoids, especially designed to give your Director project a even wider range of professional sound bites and transitions.

When used with no booleanLoopState parameter, playGroovoid will start the targeted Groovoid playing. If the targeted Groovoid is already playing, this method will be ignored. Also, if a file has been put into pause mode with the pause method, playGroovoid will make the file resume playing.

Sample Code:

on mouseUp
   global myBeatnikInstance
-- play backing groovoid as entertainment whilst we load an image off the net
   setLoop(myBeatnikInstance, TRUE)
   playGroovoid(myBeatnikInstance, TRUE, "Background-InfoPulse")
   preloadNetThing("http://www.headspace.com/images/front/web-alive.gif"
end mouseUp

Or:

-- do 2 frame transition with Groovoid and puppetTransition
-- on first frame
on mouseUp 
   global myBeatnikInstance
-- play transition Groovoid     
   playGroovoid(myBeatnikInstance, FALSE, "Fanfare-Sports")  
   go to frame+1
end mouseUp  
 
-- on next frame
on exitFrame
   puppetTransition 2  
   go to frame+1 
end exitFrame

Sets the autostart property of the targeted player. The current autostart state can be obtained using the getAutoStart method. This method is useful is preloading files by initially setting setAutoStart to false, and issuing a play(instanceName, filename)command. Once the file is preloaded, subsequent playback can be initiated by a simply play(instanceName).

Important Note:

The autostart property will affect all new files that are played using the play method.

Sample Code:

on preloadTrack -- preloads voiceover1.aif without playback straightaway
   global narrationTrk
   setAutoStart(narrationTrk,FALSE)
   play(narrationTrk,theMoviePath && "voiceover1.aif)
end preloadTrack

on mouseUp  -- on button click, start voiceover
   global narrationTrk
   play(narrationTrk)
end mouseUp

Sets the loop status of the targeted file. This can be done after a file has already been loaded. Loop state can be obtained through the musicObject using the getLoop method.

Sample Code:

on mouseUp
   global mySong
-- sprite script for Song Loop button
   setLoop(mySong, TRUE)
end mouseUP  

Stops the targeted file and unloads the song from memory. Stopped files may not be resumed with the pause method. To pause files so that they may be resumed, use the pause method. The optional second parameter fadeTimeMillisecondsInteger will ensure that the song halt occurs after the milliseconds fade time specified.

Sample Code:

on enterFrame
   global transAudio
-- stop music that has been playing during frame transition
   stop(transAudio, 1000)
end enterFrame

Playing Individual Notes

The methods in this section control an instance of the musicObject designed to play individual note events triggered purely via Lingo. This approach is useful for applications such as music courseware where you're required to perform a sequence of discrete musical notes, or playback of simple user-interface sounds based on instrumental notes. More advanced applications include new applications for self-generative music purely through logic embodied in Lingo programming.

IMPORTANT NOTE:

For the methods in this "Playing Individual Notes" section to function correctly, a 'blank' musicObject instance must be created so that these methods can reference this instance, and the instance itself does not play any notes embedded within the targetted file. Unlike older versions of the Beatnik Player for Web browsers (versions prior to 1.3.1), you do not need a "stub.rmf". Just create an instance, and it will respond accurately to the following methods.

The noteOff method will switch off a note which is currently playing. In order to specify the exact note, it is necessary to specify the MIDI channel, note number, and velocity used to switch the note on. If no note is currently playing with the specified properties, this method is ignored. noteOff may also be used to turn off notes which have been turned on using the playNote method.

Syntax Variations:

noteOff(objectMe, integerMIDIChannelNum)

By only specifying a MIDI channel number, the noteOff method will switch off all notes that are currently playing on the specified MIDI channel. This only applies, however, to notes that were turned on using musicObject's noteOn method, and does not apply to notes that were turned on from inside a MIDI or RMF file. The method is still useful, however, for user interface sonification that is done entirely through scripted note playing. The noteOn/noteOff methods are only supported for RMF (.rmf) files.

Sample Code:

on mouseDown
   global stub
-- play note on channel 16 Bank 1, Program 1 (piano) at velocity 120
   noteOn(stub,16,1,1,64,120) 
end mouseDown

on mouseUp
   global stub
   noteOff(stub,16,64,120) -- turn previous note off
end mouseUp

on mouseUp
   global stub
   noteOff(stub,16) -- turns all notes off on Channel 16
end mouseUp

Starts a note playing on a specified MIDI channel number, with the specified bank/program, note number and velocity. The note will continue to be sustained indefinitely unless switched off using the noteOff method.

Sample Code:

on mouseDown
   global stub
-- play note on channel 16, Bank 1, Program 1 (piano) at velocity 120
   noteOn(stub,16,1,1,64,120) 
end mouseDown

on mouseUp
   global stub
   noteOff(stub,16,64,120) -- turn previous note off
end mouseUp

on mouseUp
   global stub
   noteOff(stub,16) -- turns all notes off on Channel 16
end mouseUp

Issues a note to the specified MIDI channel, of the specified note number, velocity, and duration. It is important to remember that note duration is measured in milliseconds (1/1000th of a second) as opposed to Lingo ticks (1/60 second). Notes which are started using playNote may also be switched off using noteOff, even before their duration has expired. To do this, it is necessary to target the note using the correct MIDI channel, note number, and velocity used in the initial playNote call. Only RMF files are supported for playNote and it is highly recommended that you use the "stub.rmf" file provided.

Sample Code:

on mouseEnter
-- play a minor chord with the Special Bank's string sound
-- for one second on entering a Sprite's active area.
   playNote(stub,3,1,51,64,127,1000)
   playNote(stub,3,1,51,67,127,1000) 
   playNote(stub,3,1,51,71,127,1000) 
end mouseEnter

Realtime Control of Files

Useful for implementing general user interface controls, as well as controlling playback of music tracks, atmospheric soundbeds and audio transitions, these methods provide a number of ways to control in detail the playback of RMF and MIDI music files. Used imaginatively, you may have a multitracked piece of background music that responds to user initiated events. on mouseDown, on keyDown, control of MIAWs or any other interface interaction can subtly or radically modify the background musical texture, introduce other timbral layers or sound effects, having audio cues follow onscreen objects by panning in the stereo field - and more! Besides the examples found included with this documentation, be sure to visit the Beatnik Showcase at Headspace to hear and see more cutting edge examples. Remember that the web-based Beatnik Player for Netscape and Internet Explorer has all the same capabilities as the Beatnik Xtra for Director - all methods in this and other sections have their counterparts in JavaScript and may be controlled through a web page.

Mutes or unmutes the specified channel (1-16) based upon the boolean value used in the method. Using true will mute a channel and using false will unmute a channel. A channel's current mute status can be obtained by using the getChannelMute method. A non-standard MIDI implementation allows you to specify channel 0 (zero), which will alter all channels simultaneously.

For a more comprehesive explanation of mute and solo and how they interact with each other, consult the Mute and Solo documentation.

Note:

Only supported for RMF (.rmf) files and MIDI (.mid) files. To use wav, aiff, au or mod samples, you must convert them into RMF format. Consult the Beatnik Editor for Macintosh and Beatnik Convertor for Windows for tutorials on this topic.

Sample Code:

-- on button click, mutes voice-over on channel 1 of TV jingle song
on mouseUp
   setChannelMute(TVsubmixSong,1,TRUE)
end mouseUp

Sets the solo status of the specified channel (1-16) based upon the boolean value used in the method. Using true will solo a channel and using false will unsolo a channel. A channel's current solo status can be obtained by using the getChannelSolo method. For a more comprehesive explanation of mute and solo and how they interact with each other, consult the Mute and Solo documentation. A non-standard MIDI implementation allows you to specify channel 0 (zero), which will alter all channels simultaneously.

Note:

Only supported for RMF (.rmf) files and MIDI (.mid) files. To use wav, aiff, au or mod samples, you must convert them into RMF format. Consult the Beatnik Editor for Mac and Beatnik Convertor for Windows for tutorials on this topic.

Sample Code:

-- multiVoiceOver instance is RMF file with seperate voiceovers 
-- samples recorded on MIDI channels 1 - 6 for different languages.
-- on mouse click, we change to the next language channel

global languageChannel
 
on mouseUp
   set languageChannel = languageChannel + 1
   if languageChannel > 6 then set languageChannel = 1
   setChannelSolo(multiVoiceOver,languageChannel,TRUE)
end mouseUp

"MIDI Controller Changes" are a powerful feature of controlling "on-the-fly" the software wavetable MIDI synthesiser inside the Beatnik Xtra. By familiarising yourself with MIDI Controller Change options, you may control certain synthesiser settings of a RMF or MIDI file as it's playing back. A non-standard MIDI implementation allows you to specify channel 0 (zero), which will alter all channels simultaneously.

Note:

Only supported for RMF (.rmf) files and MIDI (.mid) files. To use wav, aiff, au or mod samples, you must convert them into RMF format. Consult the Beatnik Editor for Macintosh and Beatnik Convertor for Windows for tutorials on this topic.

Sample Code:

-- fade Channel 10 (drums) whilst the rest of the RMF song 
-- continues at full volume
on fadeDrums
   repeat with i = 127 down to 0
      setController(rmfSong,10,7,i)
      -- repeat loop delay for demonstration only. In real life,
      -- use a threaded implementation to avoid locking user out
      repeat with j = 1 to 8000
         updateStage
      end repeat
   end repeat
end fadeDrums

Or:

-- Pan an atmospheric sound effect in 180 degree stereo field
-- in response to a user's control of a QuickTime VR panorama.
-- For a true 360 degree implementation, front and back would
-- be implemented by linking stereo pan to setVolume as well.
--
-- panPosition's valid values are integer -100 to +100
-- (this demo handler uses the same pan range as the
-- Beatnik Stereo Pan Behaviour)

on panSurroundSound panPosition
-- MIDI Controller 10 = pan, normal valid MIDI range is 0 to 127
-- following line calculates panPosition's -100 to 100
-- to MIDI Controller 10's 0 to 127 range.
  set i = integer((panPosition+201)/1.5625-65)
  if (i<0) then set i=0
  if (i>127) then set i=127
-- Channel parameter is set to 0 to effect ALL MIDI channels
  setController(atomicGeneratorSFX,0,10,i)
end panSurroundSound

Issues a program change (altering the 'instrumental' sound of the channel) to the specified MIDI Channel with the specified program number. There are three sound banks available in Beatnik - each bank has 128 sounds. The General MIDI (0) bank conforms to the General MIDI (GM) instrument standard, with standardised instrument numbers. The Special Bank (1) has a number of alternative sounds designed to complement the GM bank, having subtle or wilder variations to the GM sounds. Many of the instruments are mapped to the same program number so that you want simply change to the Special Bank for a quick variation on the GM sound. The User Bank (2) contains custom instruments that you create with the Beatnik Editor for Macintosh, enabling custom samples to be encapsulate as a 'virtual sampler' and synchronised to MIDI songs. Since a RMF or MIDI file has 16 instrument Channels, setProgram enables you to change each Channel to different instruments. By creating sounds for the User Bank, you may have up to 384 different instruments available for each 16 channel, in addition to a range of single key sounds available in the percussion bank (only available for Channel 10).

Variation:

setProgram(objectMe, integerMIDIChannelNum, integerBankNum, integerProgramNum)

Same as the basic setProgram method except that it is overloaded to accept a bank number as well. This makes it easy to select a specific program of a specific bank in a one-step operation. Consult the instrument list for the full list of available instruments. A non-standard MIDI implementation allows you to specify channel 0 (zero), which will alter all channels simultaneously.

Note:

Only supported for RMF (.rmf) files and MIDI (.mid) files. To use wav, aiff, au or mod samples, you must convert them into RMF format. Consult the Beatnik Editor for Macintosh and Beatnik Convertor for Windows for tutorials on this topic.

Sample Code:

-- set the Channel 2 instrument to a piano in the Special Bank
setProgram(beatnik,2,0,1,1) 
playNote(beatnik,2,38,127,1000)

Used to set the reverb type for playback. Reverb is a system wide setting - multiple instances of the musicObject will all share the same reverb setting. The Beatnik Xtra Lite has a small range of reverbs - by upgrading to the Beatnik Xtra Pro, a wider range of reverbs and other digital effects are available.

Only RMF files can have reverb settings preset during authoring, which can be altered during playback with setReverbType. Be careful to always save your RMF files with a specific reverb set, unless you know that there will be several instances in your Director project and it's appropriate for them to all "inherit" the same reverb setting. The system's reverb type will change to a preset reverb type within a RMF file.. To setup reverb type during authoring for RMF files, you need to specify a reverb in the "Song Settings ..." dialog in the Beatnik Editor for Macintosh.

Note:

All supported file types (RMF, MIDI, WAV, AIFF, MOD and AU) are affected by setReverbType, making it a useful way to add dynamically controlled reverb to sample files as well as RMF and MIDI.

RMF file's user instruments can have reverb turned off (ie. dry), thus providing a blend of wet and dry instrumental mixes within the same file. Consult the Beatnik Editor for Macintosh's documentation for more information.

The standard General MIDI bank's percussion instruments (ie. Channel 10) already has dry/web instruments preset and is not affected by setReverbType. To create your own reverbed mix of percussion sounds, copy them into the user bank and reconfigure. The reverb types in the Beatnik Xtra are a subset of more specialised digital effects only available in the Xtra Pro, including higher quality reverbs and contemporary electronica effects. The replicated reverb type numbers are to maintain basic compatibility with RMF files composed for delivery via internet using the Beatnik Player's six different reverbs.

Sample Code:

-- all musicObject instances will change to no reverb
on noReverb
   setReverbType(beatnik,1)
end noReverb

-- all musicObject instances will change to acoustic lab
on midReverb
   setReverbType(beatnik,2)
end midReverb

For the targetted musicObject instance, sets the tempo (playback speed) of the targeted file to a new absolute value. The new value is not calculated from the current playing tempo. ie. setTempo(beatnik, 50) = 50 beats per minute, setTempo(beatnik, 160) = 160 beats per minute. Each RMF or MIDI file has an individual tempo setting. Valid tempo range is from 0 to 300.

In order to affect the tempo in a way which relates to the current tempo, you should use getTempo to poll the current playing tempo, use Lingo to modify that value (eg. add/subtract or multiply it by a factor), and then call setTempo with that new modified value.

Note:

Can only be used while a song is playing and has no effect if a song is stopped. Playing automatically resets any tempo which was set while a song was stopped to the song's internal tempo setting.

Only supported for RMF (.rmf) files and MIDI (.mid) files. setTempo has no meaning for wav, aiff, au or mod samples. To playback supported samples at faster or slower speeds (similar to speeding up or slowing down a tape recorder), you must convert them into a user instrument in a RMF format file. This has the side advantage of being able to simultaneously playback multiple notes at different pitches/speeds based on the same sample, as well as providing reverb, better file compression settings and encrypted watermarking. Consult the Beatnik Editor for Macintosh for tutorials on this topic.

Sample Code:

-- where tempoValue is from 0 to 100
on tempoSlider tempoValue
  set beatnikTempo = tempoValue * 3
  setTempo(beatnik,beatnikTempo)
end tempoSlider

For RMF or MIDI songs, Beatnik will handle playback of up to 64 discrete channels. setTrackMute mutes or unmutes the specified track based upon the boolean value used in the method. Using TRUE will mute a track and using FALSE will unmute a track. A track's current mute status can be obtained by using the getTrackMute method.

Note:

setTrackMute is not suitable for long sustained samples within tracks. Use setController(objectMe, integerMIDIChannelNum, 7, 1 or 127) to toggle sustained samples on and off instead. This however will have the restriction of affecting all tracks using that MIDI channel, as opposed to discrete control over 64 RMF or MIDI tracks.

Only supported for RMF (.rmf) files and MIDI (.mid) files. For a more comprehesive explanation of mute and solo and how they interact with each other, consult the Mute and Solo documentation.

Sample Code:

-- Various submixes of bass lines are in tracks 30-39.
-- This handler will successively advance through
-- the various bass line options available in song.

global currentBassTrk

on getNextBassLine
   repeat with i = 30 to 39
      setTrackMute(mySong,i,TRUE) -- mute all bass trks off first
   end repeat
   set currentBassTrk = currentBassTrk + 1
   setTrackMute(mySong,currentBassTrk,FALSE) -- unmute new bass track
end getNextBassLine

Sets the solo status of the specified track based upon the boolean value used in the method. Using true will solo a track and using false will unsolo a track. A track's current solo status can be obtained by using the getTrackSolo method.

Notes:

For a more comprehesive explanation of mute and solo and how they interact with each other, consult the Mute and Solo documentation. A non-standard MIDI implementation allows you to specify channel 0 (zero), which will alter all channels simultaneously.

Only supported for RMF (.rmf) files and MIDI (.mid) files. To use wav, aiff, au or mod samples, you must convert them into RMF format. Consult the Beatnik Editor for Macintosh and Beatnik Convertor for Windows for tutorials on this topic.

-- africanPercussion instance is RMF file with different African
-- percussion tracks on MIDI tracks 20-40.
-- on mouse click, we change to the next regional percussion instrument.

global regionalChannel
   
on mouseUp
   set regionalChannel = regionalChannel + 1
   if regionalChannel > 41 then set regionalChannel = 20
   setTrackSolo(africanPercussion,regionalChannel,TRUE)
end mouseUp

Sets the pitch transposition value in semitone intervals of only the targeted file (musical intervals are often also referred to as half notes or semitones). integerMusicalSemitoneIntervals is an absolute value and setting it to equal zero (0) will reset transposition to the original key of the file. Continually changing integerMusicalSemitoneIntervals has no cumulative effect.

For example, if you setTranspose(objectMe,12), the file will transpose up by a complete octave but, if you issue that instruction again, the file simply remains at the current transposition. If you setTranspose(objectMe,0) the file will return to playing the default pitch of the file's initial loaded state.

Note:

Only supported for RMF (.rmf) files and MIDI (.mid) files. To playback supported samples files at higher or lower pitches (similar to speeding up or slowing down a tape recorder), you must convert them into a user instrument in a RMF format file. This has the side advantage of being able to simultaneously playback multiple notes at different pitches based on the same sample, as well as providing reverb, better file compression settings and encrypted watermarking. Consult the Beatnik Editor for Macintosh and Beatnik Convertor for Windows for tutorials on this topic.

Sample Code:

-- jazzPlayAlongSong instance can be transposed at will
-- to enable students to practise soloing in different keys
-- following button script shifts key up one semitone

global currentKey
   
on mouseUp
   set currentKey = currentKey + 1
   -- this handler resets octave transposition
   -- to original pitch ie. no transposition
   if currentKey > 11 then set currentKey = 0
   setTranspose(jazzPlayAlongSong,currentKey)
end mouseUp

Sets the overall playback volume for the targeted musicObject instance. This is different to setting the individual volumes for MIDI channels in a music file, which can be done using MIDI Controller Change 7 with the setController method. Each music object instance has its own volume setting.

Sample Code:

on initVolume
-- initialize volume settings for all music and SFX
   setVolume(popJingle,40)
   setVolume(narration,70)
   setVolume(GUIsounds,55)
end initVolume

Obtaining Playback State Information

Comprehensive playback properties can be obtained via these methods. These properties are generally set with their companion methods in the Realtime Control of Files and Song Control and Player Properties sections. By obtaining the current playback status of various song properties, one may make decisions to for your movie. eg. if the song is stopped, load the next song or display a message; if the song volume is set below a threshold, alter the color scheme of the user interface; poll getController for certain conditions of embedded MIDI Control Change information and execute handlers based on embedded MIDI information over time.

All of the methods listed below return values that indicate state information about the targeted Beatnik Player. They may be used in assignment statements, conditional statements, or expressions. The type of the value returned by each method (ie. string, integer, or boolean) is specified in the description for each method.

Returns boolean TRUE if a file is currently in a paused state or FALSE if a file is in a play or stopped state. By testing isPaused, you may build your own GUI song transport controls, or jump to a different frame, open a Movie-In-A-window or any number of applications.

Sample Code:

-- for a kiosk application, if the narration
-- voice over is paused, turn on help screen
-- so user may select narration in other languages

on checkNarrationPaused
   if (isPaused(kioskVoiceOver)) then
      selectOtherLanguageOptions
   end if
end checkNarrationPaused

Returns boolean TRUE if a file is currently playing or FALSE if a file is in a paused or stopped state. See also the isPaused method. By testing isPlaying in conjunction with isPaused, you may tell if a file has been stopped or paused. As an example, a jukebox application can load a new song on a playlist, as the musicObject will automatically stop once a playing file has reached the last song position.

Sample Code:

-- for a jukebox application, if the current song
-- has stopped, then retrieve the next song title from
-- the playlist, and start playing automatically.
-- this handler would be polled periodically,
-- either by a timer or on exitFrame as examples.

on checkForNextSong, playListIndex
   set playList = ["techno.rmf","classical.rmf","ambient.rmf","house.rmf"]
   if (not(isPlaying(currentSong) and not(isPaused(currentSong)) then
      set songTitle = getAt(playList,playListIndex)
      setAutoStart(currentSong, TRUE)
      play(currentSong)
   end if
end checkForNextSong

Returns the current mute status of the specified MIDI channel. A value of true indicates that the channel is muted, and a value of false indicates that it is not muted. A channel's mute status can be set using the setChannelMute method.

Note:

Returns a boolean in the range of {true or false}. For a more comprehesive explanation of mute and solo and how they interact with each other, consult the Mute and Solo documentation. Only supported for RMF (.rmf) files and MIDI (.mid) files

Sample Code:

-- for a typical Enhanced CD remixer, check which
-- channel has been muted by user and return
-- status for further 'music-video' animations 
-- triggered by channel mutes.
on init
   global channelList
   set channelList = [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
end init

on checkWhichChannelsMuted
   global channelList
   repeat with i = 1 to 16
      if (getChannelMute(enhancedCDRemixer,i)) then
          setAt(channelList,i,TRUE)
      end if
   end repeat
   return channelList
end checkWhichChannelsMuted

Returns the current solo status of the specified MIDI channel. A value of true indicates that the channel is soloed, and a value of false indicates that it is not soloed. A channel's solo status can be set using the setChannelMute method.

Note:

Returns a boolean in the range of {true or false}. For a more comprehesive explanation of mute and solo and how they interact with each other, consult the Mute and Solo documentation. Only supported for RMF (.rmf) files and MIDI (.mid) files.

Sample Code:

-- In a music courseware application, check which
-- channel is soloed and trigger highlights for
-- the particular channel's instruments on a
-- notated music staff.

on checkWhichChannelsSoloed
   repeat with i = 1 to 16
      if (getChannelSolo(orchestra,i)) then
          highlightInstrument i
      end if
   end repeat
end checkWhichChannelsSoloed

Gets the value of the specified MIDI controller on the specified MIDI channel. See the setController method for the full range of MIDI Controller Changes supported by the Beatnik Xtra.

Note:

Returns a value in the range of {0-127}. Only supported for RMF (.rmf) files and MIDI (.mid) files

Sample Code:

-- retrieve modulation wheel settings in dummy track to
-- control animation locV height synced to music track
on modWheeltoLocV
   set spriteLocV = getController(animationSyncMaster,1,1)
   return spriteLocV
end modWheeltoLocV

Or:

-- retrieve modulation wheel settings in dummy track to
-- synchronise ShockWave Flash frames to music track
on modWheeltoFlashFrame
   set flashFrame = getController(animationSyncMaster,16,1)
   set the frame of sprite 15 to flashFrame
end modWheeltoFlashFrame

Gets the current loop status of the musicObject instance (TRUE or FALSE). The loop status can be set with the setLoop method, play or playGroovoid methods.

Sample Code:

-- Check if song has been looped by user settings
on checkLoop
   set x = getLoop(karaokeSong)
   return x
end checkLoop

Note:

Returns a value in the range of {0-127}. Only supported for RMF (.rmf) files and MIDI (.mid) files

Sample Code:

-- display current program that user has selected for
-- onscreen synth keyboard
on getTimbre
   set i = getProgram(synth,1)
   set timbreName = getAt(timbreList,i)
   put timbreName into member timbreField
end getTimbre

Gets the current reverb type as set by the setReverbType method.

Note:

Returns a value in the range of {0-6} [Temporary: Still to be finalised for Beatnik Xtra Lite.]

Sample Code:

-- check reverb and display reverb name
on checkReverb
  set i = getReverbType(raveSong)
  set j = getAt(reverbList,i)
  put j into member reverbNameField
end checkReverb

Gets the current playing tempo value (measured in beats per minute) as set by the setTempo method and file's initial playing tempo.

Note:

Returns a value in bpm (beats per minute)
only supported for RMF (.rmf) files and MIDI (.mid) files

Sample Code:

-- increase tempo by 10 bpm
on bumpUpTempo
   set i = getTempo(mySong) + 10
   setTempo(mySong,i)
end bumpUpTempo

Returns the current mute status of the specified track. A value of true indicates that the track is muted, and a value of false indicates that it is not muted. A track's mute status can be set using the setTrackMute method.

Note:

Returns a boolean in the range of {true or false}. For a more comprehesive explanation of mute and solo and how they interact with each other, consult the Mute and Solo documentation. Only supported for RMF (.rmf) files and MIDI (.mid) files

Sample Code:

-- if drum track is muted then turn off drum icon sprite
if (getTrackMute(jazzBand,24)) then
   set the visible of sprite drumIcon to 0
end if

Returns the current solo status of the specified track. A total of 64 tracks can be supported in any RMF or MIDI file. A value of true indicates that the track is soloed, and a value of false indicates that it is not soloed. A track's solo status can be set using the setTrackSolo method.

Note:

Returns a boolean in the range of {true or false}
For a more comprehesive explanation of mute and solo and how they interact with each other, consult the Mute and Solo documentation.
only supported for RMF (.rmf) files and MIDI (.mid) files

Sample Code:

-- check if current track is soloed
on checkSolo thisTrack
   set i = getTrackSolo(salsaGroove,thisTrack)
   return i
end checkSolo

Gets the current tranposition value for the targeted file as set by the setTranspose method.

Note:

Returns a value in musical intervals
only supported for RMF (.rmf) files and MIDI (.mid) files

Sample Code:

-- displays tranposition interval of current song,
-- handler translates only for major and minor intervals
-- and does not account for augmented intervals.

on displayTranposition
   global blueExercise1
   set i = getTranspose(blueExercise1)
   set j = ["minor 2nd","major 2nd","minor 3rd","major 3rd",
            "perfect 4th", "diminished 5th","minor 6th",
            "major 6th","minor 7th","major 7th","octave"]
   if (i<0) then
      set dir = "downwards"
      set i = i * -1
   else
      set dir = "upwards"
   end if

   if (i=0) then 
      set k = "at tonic pitch"
      set dir = ""
   else
      set k = getAt(j,i) && dir
   end if
   put k into member tranpositionField
end displayTranposition

Returns the current overall playback volume as set by setVolume, or the song when first initialized. Valid parameters are from 0 to 100.

Sample Code:

-- set volume to 10% lower of current volume
on lowerTenPercentVol
   set i = getVolume(mySong)
   set i = i - (i/10)
   setVolume(mySong,i)
end lowerTenPercentVol

©Copyright 1998 by Headspace, Inc. All rights reserved.

End of Document.